package xx.services.entity.inter;

import java.io.InputStream;

import javax.ws.rs.FormParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MultivaluedMap;

/**
 * 实体服务接口<br>
 * 
 * @Path (Constants.RESTFUL_ROOT_PATH + "/{entity}") {entity}根据不用的类型不一样，如产品应该为product，文章应用为article
 * @author chenx
 */
public interface IEntityInterface
{
    /**
     * 增加根分类
     * 
     * @POST
     * @Path ("/category")
     * @param name
     *            -@FormParam("name") 分类名称
     * @param keyword
     *            -@FormParam("keyword") 关键字
     * @param description
     *            -@FormParam("description") 分类描述
     * @return 新增的分类实体
     */
    public String addCategoryRoot(@FormParam("name")
    String name, @FormParam("keyword")
    String keyword, @FormParam("description")
    String description);

    /**
     * 添加与实体{entity_id}关联的附件。<br>
     * 注：附件名称与描述通过fileId从Xfile中获取。
     * 
     * @POST
     * @Path ("/{entity_id}/attach")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @param fileId
     *            -@FormParam("file_id") 文件ID，关联Xfile
     * @param description
     *            -@FormParam("description") 附件描述
     * @return 添加的Xfile实体
     * @author dengjinye,2010-10-29
     */
    public String addAttach(@PathParam("entity_id")
    long entityId, @FormParam("file_id")
    long fileId, @FormParam("description")
    String description);

    /**
     * 添加对实体{entity_id}的评论。<br>
     * 
     * @POST
     * @Path ("/{entity_id}/comment")
     * @param entityId
     *            实体id
     * @param title
     *            标题
     * @param content
     *            内容
     * @return
     * @author dengjinye,2011-1-25
     */
    public String addComment(@PathParam("entity_id")
    long entityId, @FormParam("title")
    String title, @FormParam("content")
    String content);

    /**
     * 添加与实体{entity_id}关联的心情描述。<br>
     * 注：每个实体最多只能添加一次心情描述，心情描述ID从心情表(mood)中取出，放到实体与心情的关联表中
     * 
     * @POST
     * @Path ("/{entity_id}/mood")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @return 添加的mood列表
     * @author dengjinye,2010-10-29
     */
    public String addMood(@PathParam("entity_id")
    long entityId);

    /**
     * 添加与实体{entity_id}关联的祭拜。<br>
     * 注：每个实体最多只能添加一次祭拜，祭拜ID从祭拜表(sacrifice)中取出，放到实体与祭拜的关联表中
     * 
     * @POST
     * @Path ("/{entity_id}/sacrifice")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @return 添加的sacrifice列表
     * @author dengjinye,2010-10-29
     */
    public String addSacrifice(@PathParam("entity_id")
    long entityId);

    /**
     * 添加与实体{entity_id}关联的图片。<br>
     * 注：图片名称与描述通过fileId从Xfile中获取。
     * 
     * @POST
     * @Path ("/{entity_id}/picture")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @param fileId
     *            -@FormParam("file_id") 文件ID，关联Xfile
     * @param description
     *            -@FormParam("description") 图片描述
     * @return 添加的Xfile实体
     * @author dengjinye,2010-10-29
     */
    public String addPicture(@PathParam("entity_id")
    long entityId, @FormParam("file_id")
    long fileId, @FormParam("description")
    String description);

    /**
     * 修改实体{entity_id}的名称等。
     * 
     * @PUT
     * @Path ("/{entity_id}")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @param title
     *            -@FormParam("title") 实体标题
     * @param content
     *            -@FormParam("content") 实体内容
     * @param url
     *            -@FormParam("url") 指定URL地址
     * @param fileId
     *            -@FormParam("file_id") 关联实体ID
     * @param tags
     *            -@FormParam("tags") 实体tag标签，多个tag标签用空格“ ”隔开
     * @param value-@FormParam("value")
     *            实体的扩展属性值
     * @return 修改后的实体
     * @author dengjinye,2010-12-6
     */
    public String updateEntity(@PathParam("entity_id")
    long entityId, @FormParam("title")
    String title, @FormParam("content")
    String content, @FormParam("url")
    String url, @FormParam("file_id")
    long fileId, @FormParam("tags")
    String tags, MultivaluedMap<String, String> formParams);

    /**
     * 移动实体
     * 
     * @PUT
     * @Path ("/{category_id}/{entity_id}/moveto/{to_category_id}")
     * @param categoryId
     *            原分组id
     * @param entityId
     *            多个实体间用"_"间隔
     * @param toCategoryId
     *            目标分组id
     * @return
     */
    public String moveEntity(@PathParam("category_id")
    long categoryId, @PathParam("entity_id")
    String entityId, @PathParam("to_category_id")
    long toCategoryId);

    /**
     * 复制实体
     * 
     * @POST
     * @Path ("/{category_id}/{entity_id}/copyto/{to_category_id}")
     * @param categoryId
     * @param entityId
     * @param toCategoryId
     * @return
     */
    public String copyEntity(@PathParam("category_id")
    long categoryId, @PathParam("entity_id")
    String entityId, @PathParam("to_category_id")
    String toCategoryId);

    /**
     * 1）此接口为受保护接口；2）删除实体{entity_id}，同时也会删除与之关联的实体数据。
     * 
     * @DELETE
     * @Path ("/{entity_id}")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID，多个实体ID用“_”连接起来
     * @param categoryId
     *            实体与在的分组ID
     * @return String 下午09:27:05
     * @author dengjinye
     */
    public String deleteEntity(@PathParam("entity_id")
    String entityId, long categoryId);

    /**
     * 获取实体对应的根分类列表
     * 
     * @GET
     * @Path ("/category")
     * @return Category分类列表
     */
    public String getCategoryRoot();

    /**
     * 获取实体{entity_id}的详细信息等(包含关联实体数据)。<br>
     * 注：如果不是从管理后台进入，需要对实体的访问量(total)加1
     * 
     * @GET
     * @Path ("/{entity_id}")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @param jsonkeys
     *            -@QueryParam("jsonkeys") 需要返回关联的数据对应用的JSONkey<br>
     *            多个JSONkey用逗号“,”隔开，Jsonkey从实体API中获取。<br>
     * @return Entity实体
     * @author dengjinye
     */
    public String getEntity(@PathParam("entity_id")
    long entityId, @QueryParam("jsonkeys")
    String jsonkeys);

    /**
     * 描述：1）此接口为公共接口；2）获取与实体{entity_id}关联的附件列表。
     * 
     * @GET
     * @Path ("/{entity_id}/attach")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @return 实体对应的附件列表
     * @author dengjinye,2010-10-29
     */
    public String getAttachList(@PathParam("entity_id")
    long entityId);

    /**
     * 描述：获取关联实体评论列表，按日期排序，最新的排在最前面
     * 
     * @GET
     * @Path ("/{entity_id}/comment")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @return 实体对应的评论列表
     */
    public String getCommentList(@PathParam("entity_id")
    long entityId);

    /**
     * 获取与实体{entity_id}关联的心情。
     * 
     * @GET
     * @Path ("/{entity_id}/mood")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @return 实体对应的心情列表
     * @author dengjinye,2010-10-29
     */
    public String getMoodList(@PathParam("entity_id")
    long entityId);

    /**
     * 获取与实体{entity_id}关联的图片集。
     * 
     * @GET
     * @Path ("/{entity_id}/picture")
     * @param entityId
     *            -@PathParam("entity_id") 指定实体ID
     * @return 实体对应的图片列表
     * @author dengjinye,2010-10-29
     */
    public String getPictureList(@PathParam("entity_id")
    long entityId);

    /**
     * 获取与实体{entity_id}关联的祭拜。
     * 
     * @GET
     * @Path ("/{entity_id}/sacrifice")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @return 实体对应的祭拜列表
     * @author dengjinye,2010-10-29
     */
    public String getSacrificeList(@PathParam("entity_id")
    long entityId);

    /**
     * 获取与实体{entity_id}关联的实体。
     * 
     * @GET
     * @Path ("/{entity_id}/relation")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @return 实体对应的关联实体列表
     */
    public String getRelation(@PathParam("entity_id")
    long entityId);

    /**
     * 增加与实体{entity_id}关联的实体。
     * 
     * @POST
     * @Path ("/{entity_id}/relation/{relation_entity_id}")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @param entityRelationId
     *            -@PathParam("relation_entity_id") 需要关联的实体ID集，多个ID用“_”隔开
     * @return 实体对应的关联实体列表
     */
    public String addRelation(@PathParam("entity_id")
    long entityId, @PathParam("relation_entity_id")
    String entityRelationId);

    /**
     * 删除与实体{entity_id}关联的实体。
     * 
     * @DELETE
     * @Path ("/{entity_id}/relation/{relation_entity_id}")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @param entityRelationId
     *            -@PathParam("relation_entity_id") 需要关联的实体ID集，多个ID用“_”隔开
     * @return 删除成功的关联实体ID
     */
    public String deleteRelation(@PathParam("entity_id")
    long entityId, @PathParam("relation_entity_id")
    String entityRelationId);

    /**
     * 对实体的支持率
     * 
     * @POST
     * @Path ("/{entity_id}/agree")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @return 最新支持率
     */
    public String agree(@PathParam("entity_id")
    long entityId);

    /**
     * 对实体的反对率
     * 
     * @POST
     * @Path ("/{entity_id}/differ")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @return 最新反对率
     */
    public String differ(@PathParam("entity_id")
    long entityId);

    /**
     * 新增实体的支付明细
     * 
     * @POST
     * @Path ("/{entity_id}/pay")
     * @param entityId
     *            实体ID
     * @param paydate
     *            支付日期
     * @param payprice
     *            支付金额
     * @param order
     *            第N次支付
     * @return
     * @author dengjinye,2013-5-29
     */
    public String addPay(@PathParam("entity_id")
    long entityId, @FormParam("paydate")
    String paydate, @FormParam("payprice")
    String payprice, @FormParam("order")
    String order);

    /**
     * 获取对实体的支付明细
     * 
     * @GET
     * @Path ("/{entity_id}/pay")
     * @param entityId
     *            -@PathParam("entity_id") 实体ID
     * @return 支付明细
     * @author dengjinye,2013-5-29
     */
    public String getPayList(@PathParam("entity_id")
    long entityId);
}
